home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / trace.n < prev    next >
Text File  |  1994-09-20  |  8KB  |  199 lines
  1.  
  2.  
  3.  
  4. trace(n)              Tcl Built-In Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      trace - Monitor variable accesses
  12.  
  13. SYNOPSIS
  14.      trace _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  15. _________________________________________________________________
  16.  
  17.  
  18. DESCRIPTION
  19.      This command causes Tcl commands  to  be  executed  whenever
  20.      certain  operations  are invoked.  At present, only variable
  21.      tracing is implemented. The legal  _o_p_t_i_o_n's  (which  may  be
  22.      abbreviated) are:
  23.  
  24.      trace variable _n_a_m_e _o_p_s _c_o_m_m_a_n_d
  25.           Arrange for _c_o_m_m_a_n_d to be  executed  whenever  variable
  26.           _n_a_m_e is accessed in one of the ways given by _o_p_s.  _N_a_m_e
  27.           may refer to a normal variable, an element of an array,
  28.           or  to  an  array as a whole (i.e. _n_a_m_e may be just the
  29.           name of an array, with  no  parenthesized  index).   If
  30.           _n_a_m_e  refers  to a whole array, then _c_o_m_m_a_n_d is invoked
  31.           whenever any element of the array is manipulated.
  32.  
  33.           _O_p_s indicates which operations  are  of  interest,  and
  34.           consists of one or more of the following letters:
  35.  
  36.                r    Invoke _c_o_m_m_a_n_d whenever the variable is read.
  37.  
  38.                w    Invoke _c_o_m_m_a_n_d whenever the variable is writ-
  39.                     ten.
  40.  
  41.                u    Invoke  _c_o_m_m_a_n_d  whenever  the  variable   is
  42.                     unset.   Variables  can  be  unset explicitly
  43.                     with the unset command,  or  implicitly  when
  44.                     procedures  return  (all of their local vari-
  45.                     ables are unset).  Variables are  also  unset
  46.                     when  interpreters  are  deleted,  but traces
  47.                     will not  be  invoked  because  there  is  no
  48.                     interpreter in which to execute them.
  49.  
  50.           When the trace triggers, three arguments  are  appended
  51.           to _c_o_m_m_a_n_d so that the actual command is as follows:
  52.  
  53.                _c_o_m_m_a_n_d _n_a_m_e_1 _n_a_m_e_2 _o_p
  54.  
  55.           _N_a_m_e_1 and _n_a_m_e_2 give the name(s) for the variable being
  56.           accessed:  if the variable is a scalar then _n_a_m_e_1 gives
  57.           the variable's name and _n_a_m_e_2 is an  empty  string;  if
  58.           the  variable  is an array element then _n_a_m_e_1 gives the
  59.           name of the array and name2 gives the  index  into  the
  60.           array;  if  an  entire  array  is being deleted and the
  61.  
  62.  
  63.  
  64. Tcl                                                             1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. trace(n)              Tcl Built-In Commands
  71.  
  72.  
  73.  
  74.           trace was registered on the overall array, rather  than
  75.           a  single  element, then _n_a_m_e_1 gives the array name and
  76.           _n_a_m_e_2 is an empty string.  _O_p indicates what  operation
  77.           is being performed on the variable, and is one of r, w,
  78.           or u as defined above.
  79.  
  80.           _C_o_m_m_a_n_d executes in the same context as the  code  that
  81.           invoked  the  traced  operation:   if  the variable was
  82.           accessed as part of a Tcl procedure, then _c_o_m_m_a_n_d  will
  83.           have  access to the same local variables as code in the
  84.           procedure.  This context may be different than the con-
  85.           text  in  which  the  trace  was  created.   If _c_o_m_m_a_n_d
  86.           invokes a procedure (which it normally does)  then  the
  87.           procedure  will  have  to  use  upvar  or uplevel if it
  88.           wishes to access the traced variable.  Note  also  that
  89.           _n_a_m_e_1  may not necessarily be the same as the name used
  90.           to set the trace  on  the  variable;   differences  can
  91.           occur  if the access is made through a variable defined
  92.           with the upvar command.
  93.  
  94.           For read and write traces, _c_o_m_m_a_n_d can modify the vari-
  95.           able  to affect the result of the traced operation.  If
  96.           _c_o_m_m_a_n_d modifies the value of a variable during a  read
  97.           or  write trace, then the new value will be returned as
  98.           the result of the traced operation.  The  return  value
  99.           from   _c_o_m_m_a_n_d  is ignored except that if it returns an
  100.           error of  any  sort  then  the  traced  operation  also
  101.           returns  an  error with the same error message returned  |
  102.           by the trace command (this mechanism  can  be  used  to
  103.           implement read-only variables, for example).  For write
  104.           traces, _c_o_m_m_a_n_d is invoked after the  variable's  value
  105.           has  been  changed;  it  can write a new value into the
  106.           variable to override the original  value  specified  in
  107.           the write operation.  To implement read-only variables,
  108.           _c_o_m_m_a_n_d will have to restore the old value of the vari-
  109.           able.
  110.  
  111.           While _c_o_m_m_a_n_d is  executing  during  a  read  or  write
  112.           trace, traces on the variable are temporarily disabled.
  113.           This means that reads and  writes  invoked  by  _c_o_m_m_a_n_d
  114.           will  occur  directly, without invoking _c_o_m_m_a_n_d (or any
  115.           other traces) again.  However, if  _c_o_m_m_a_n_d  unsets  the  |
  116.           variable then unset traces will be invoked.
  117.  
  118.           When an  unset  trace  is  invoked,  the  variable  has
  119.           already  been  deleted:  it will appear to be undefined
  120.           with no traces.  If an unset occurs because of  a  pro-
  121.           cedure  return,  then  the trace will be invoked in the
  122.           variable context of the procedure  being  returned  to:
  123.           the  stack  frame  of  the  returning procedure will no
  124.           longer exist.  Traces are  not  disabled  during  unset
  125.           traces,  so  if  an  unset  trace command creates a new
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. trace(n)              Tcl Built-In Commands
  137.  
  138.  
  139.  
  140.           trace and accesses the  variable,  the  trace  will  be
  141.           invoked.  Any errors in unset traces are ignored.        |
  142.  
  143.           If there are multiple traces on  a  variable  they  are
  144.           invoked  in  order  of creation, most-recent first.  If
  145.           one trace returns an error, then no further traces  are
  146.           invoked  for  the  variable.  If an array element has a
  147.           trace set, and there is also a trace set on  the  array
  148.           as  a  whole, the trace on the overall array is invoked
  149.           before the one on the element.
  150.  
  151.           Once created, the trace remains in effect either  until
  152.           the  trace  is  removed  with the trace vdelete command
  153.           described below, until the variable is unset, or  until
  154.           the  interpreter  is  deleted.  Unsetting an element of
  155.           array will remove any traces on that element, but  will
  156.           not remove traces on the overall array.
  157.  
  158.           This command returns an empty string.
  159.  
  160.      trace vdelete _n_a_m_e _o_p_s _c_o_m_m_a_n_d
  161.           If there is a trace  set  on  variable  _n_a_m_e  with  the
  162.           operations  and  command given by _o_p_s and _c_o_m_m_a_n_d, then
  163.           the trace is removed, so that _c_o_m_m_a_n_d will never  again
  164.           be invoked.  Returns an empty string.
  165.  
  166.      trace vinfo _n_a_m_e
  167.           Returns a list containing one element  for  each  trace
  168.           currently  set  on  variable _n_a_m_e.  Each element of the
  169.           list is itself a list containing  two  elements,  which
  170.           are  the _o_p_s and _c_o_m_m_a_n_d associated with the trace.  If
  171.           _n_a_m_e doesn't exist or doesn't have any traces set, then
  172.           the result of the command will be an empty string.
  173.  
  174.  
  175. KEYWORDS
  176.      read, variable, write, trace, unset
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.